package com.smart.community.region.service;

import com.smart.community.feign.region.dto.RegionHierarchyInfo;

import java.util.List;
import java.util.Map;

/**
 * 区域层级关系服务接口
 * 
 * 提供房户层级向上追溯的核心服务，支持缴费系统根据房户ID快速定位物业公司
 * 业务流程：房户ID → 单元ID → 楼栋ID → 社区ID → 物业公司ID
 * 
 * @author Wu.Liang
 * @version 1.0.0
 * @since 2025-01-30
 */
public interface IRegionHierarchyService {
    
    /**
     * 根据房户ID获取所属物业公司ID
     * 
     * 核心缴费接口：通过房户ID直接获取物业公司ID，用于获取收款二维码
     * 查询路径：房户 → 单元 → 楼栋 → 社区 → 物业公司
     * 
     * @param householdId 房户ID
     * @return 物业公司ID，如果查询失败或无关联返回null
     */
    Long getPropertyCompanyIdByHouseholdId(Long householdId);
    
    /**
     * 根据房户ID获取完整的层级信息
     * 
     * 返回房户所属的单元、楼栋、社区、物业公司的完整ID和名称信息
     * 用于需要展示完整层级路径的业务场景
     * 
     * @param householdId 房户ID
     * @return 层级信息对象，包含各级ID和名称
     */
    RegionHierarchyInfo getRegionHierarchyByHouseholdId(Long householdId);
    
    /**
     * 批量根据房户ID获取物业公司ID
     * 
     * 用于批量缴费、批量查询等场景，提高查询效率
     * 返回房户ID与物业公司ID的映射关系
     * 
     * @param householdIds 房户ID列表
     * @return 房户ID与物业公司ID的映射关系，key为房户ID，value为物业公司ID
     */
    Map<Long, Long> getPropertyCompanyIdsByHouseholdIds(List<Long> householdIds);
    
    /**
     * 根据房户ID获取社区ID
     * 
     * 用于需要社区级别权限控制或社区数据统计的场景
     * 查询路径：房户 → 单元 → 楼栋 → 社区
     * 
     * @param householdId 房户ID
     * @return 社区ID，如果查询失败返回null
     */
    Long getCommunityIdByHouseholdId(Long householdId);
    
    /**
     * 批量根据房户ID获取社区ID
     * 
     * 用于批量社区数据查询，支持跨社区的数据统计和权限控制
     * 
     * @param householdIds 房户ID列表
     * @return 房户ID与社区ID的映射关系，key为房户ID，value为社区ID
     */
    Map<Long, Long> getCommunityIdsByHouseholdIds(List<Long> householdIds);
}
